// ==================================================================================
// Shared Genomics Project MPI Codebase
// Version 1.0 30/04/2010
//
// (c) 2010 University of Manchester all rights reserved
//
// This file is distributed under the GNU General Public License, Version 2.  
// Please see the file COPYING.txt for more details
// ==================================================================================

#ifndef _PERMFILE_H_
#define _PERMFILE_H_

#include <stdlib.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
\file
\ingroup	gio
\brief		Permutation Indices File
\details
	This header allows the creation of an permutation indices file (PERM file)
	which contains a series of randomised arrays of size 'N'.<br>
	The PERM file is used to co-ordinate randomised calculations if data is distributed
	across the cores of the NIBHI cluster.<br>
	Typically a PERM file uses the suffix \ref SUFFIX_PERM_FILE .
*/

/*!
\brief Create a permutation indices file.
\details
	The output filename is bound to \ref selected_options::szPermFileName.
\param [in] ops Output file location
\param [in] nRows No. of permutations to be written to the indices file.
\param [in] nColumns No. of elements in the randomised array
\returns 1 on success, 0 on failure
*/
int permfile_create(struct selected_options *ops, int nRows, int nColumns);

/*!
\brief Load a PERM file.
\details The input filename is bound to \ref selected_options::szPermFileName.
\param [in] ops Input file location
\param [in] nRows Pointer to store the No. arrays in the file.
\param [in] nColumns Pointer to store the width of each array in file.
\return contiguous array of integers or NULL on failure.
*/
int* permfile_load(struct selected_options *ops, int *nRows, int *nColumns);

/*!
\brief Create a permutation indices file and copy to a remote directory.
\details
	The output filename is a concatonation of \ref selected_options::rdir,
	\ref selected_options::szRunId and \ref SUFFIX_PERM_FILE . 
\param [in] ops Output file location
\param [in] nRows No. of permutations to be written to the indices file.
\param [in] nColumns No. of elements in the randomised array
\param [in] rank Local processor rank
\returns 1 on success, 0 on failure
*/
int permfile_create_and_copy(struct selected_options *ops, int nRows, int nColumns, int rank);

#ifdef __cplusplus
}
#endif

#endif // _PERMFILE_H_
